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L Introduction 

lliis manual describes the operating system for the Alto, llie manual will be revised as the system 
changes. Parts of tlie system which are likely to be changed arc so indicated; users should try to isolate 
their use of these facilities in routines which can easily be modified, or better yet, avoid them entirely, it 
possible. 

The system and its description can be separated into two parts: 

a) User-callable procedures, which are of two kinds: standard procedures which are always 
provided, and library procedures which must be loaded with the user's program if they are 
desired, l^his manual describes only standard procedures; the library procedures are documented 
in the "Alto Packages N4anual." 

b) Data structures, such as disk files and directories, which are used by the system but which are also 
accessible to user procedures and subsystems. 

l^he system is written almost entirely in Bcpl. Its procedures are invoked with the standard Bcpl calling 
sequence, and it expects the subsystems it calls to be in the format produced by tlie Alto Bcpl loader. 



2. Hardware summary 

This section provides an overview of the Alto Hardware. Briefly, every Alto has: 

a) A memory of 64k words of 16 bits each. The cycle time is 850ns. 

b) An emulator for a standard instniction set. 

c) Secondary memory, which may consist of one or two Diablo 31 cartridge disk drives, or one 
Diablo 44 cartridge disk drive. The properties of these disks are summarized in 1 able 2.2. 

d) An 875 line TV monitor on which a raster of square dots can be displayed, 606 dots wide and 808 
dots high. The display is refreshed from Alto memory under control of a list of displav control 
blocks. Each block describes what to display on a horizontal band of the screen by specifying: 

the height ofthe band, which must be even; _ . , . r-n j • u 

the width, which must be a multiple of 32; the space remaining on the right is filled with 

background^ , , , ^ . r-n ^ 

The indentation, which must be a multiple of 16; the space thus reserved on the left is filled 

with background; 
the color ofthe background, black or white; .. / . ir.ii. 

the address ofthe data (must be even), in which bits specify background. Each bitcontrols 
the color of one dot. The ordering is increasing word addresses and then bit numbers in 
memory, top to bottom and then left to right on the screen; and a half-resolution flag 
which makes each dot twice as wide and twice as high. 
There is also a 16 x 16 cursor which can be positioned anywhere on the screen. If the entire 
screen is filled at full resolution, the display takes about 60% ofthe machine cycles and30704D 
words of memory. 
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e) A 44-kcy keyboard, 5-fingcr keyset, and mouse 

A Diablo printer interfecc 

g) An Hthernet interface 

h) Interfaces for analog-to-digital and digital-to-analog conversion, for TV camera input, and for a 
RS-232b (teletype) connection 

i) A real-time clock and an interval timer (see table 2.1 for brief descriptions) 

3. User-callable procedures 

This section describes the operating system facilities provided by procedures which can be called from user 
programs using the standard Bcpl calling sequence. All of these procedures are a permanent part of the 
operating system, automatically available to any user program. 

Although this manual describes a rather extensive set of facilities, which togetlier occupy close to 12K 
words of memory, portions of the system can be deactivated (see Junta), thus freeing the memory thevuse. 
When the user program finishes execution, the deactivated portions can be retrieved from the disk and 
reinitialized. 

Default arguments: Many of the procedures given below have rather long argument lists, but have 
convenient defaulting schemes. The documentation decorates argument lists with default values. An 
argument followed by [exp] will default if omitted or zero to the value exp; an argument followed by 
[...exp] will defeult if omitted to exp. Although Bcpl allows you to omit procedure arguments by using 
nil, the called procedure cannot detect its use; it tlierefore cannot be the basis for defaulting arguments. 

3.1. Facilities 

The facilities of the operating system fall into fairly neat categories; often this is because the operating 
system has simply loaded a standard library subroudne as part of its environment. This manual offers 
summarized documentation for tlie functions in the various software "packages;" more documentation can 
be found in the "Alto Software Packages Manual." (Note: Appendices to this manual include 
documentation of the packages most relevant to the operating system.) In outline, the operating system 
provides: 

- A "basic" resident that maintains a time-of-day clock, that processes parity error interrupts, and 
that contains the resident required to interface to Swat, the debugger. 

- The Bcpl amdme support module, which provides several functions (such as a stack frame 
allocator) that are necessary to permit Bcpl programs to run. 

Disk drivers for transferring complete pages between memory and existing files on the disk. This 
is the BfsBase package. 

Disk drivers for creating new files, and for extending or shortening existing files. ITiis is the 
BfsWrite package. 

A simple storage allocator for managing "zones" of working storage. This is the Alloc package. 

- Disk "streams," which implement sequential byte or word I/O to tile disk. This is thc DiskStreams 
package. 

- Disk directory management, which provides facilides for searching directory files for entries that 
associate a string name and a disk file. 
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- A keyboard handler, which decodes keyboard interactions into a sequence of ASCII characters. 

- A display driver, which maintains a "system display," and handles tlie printing of characters on the 
display, l^his is the DspStream package. 

- Miscellaneous functions, including (1) tlie "call subsystem" function, which reads a file produced 
by the Bcpl loader into memory and executes it; (2) allocation ftmctions that manage the space not 
used by the operating system or the user code, providing a stack for the user program and fixed- 
si/e blocks that it may require; (3) the procedure for de-activatmg various portions of thcoperatmg 
system; and (4) additional utilities, 

3.2. Loading and Initialization 

The facilities of the operating system are made accessible to user programs via static variables that refer to 
system procedures or system scalars . Because these objects are not defined in your Hcpl program, you must 
declare the names to be external . The Bcpl loader, Bldr, automatically reads the file Sys.Bk, which 
describes how to arrange that your program's external references will match up with the operating system 
objects (for details, see Bldr documentation in the Bcpl manual). This arrangement does not require re- 
loading programs when objects in the operating system move. 

When a Bcpl program is read into the Alto memory, all of the system procedures described below willhave 
been initialized. A region is reserved for allocating system objects (e.g., disk streams); currently about 6 
disk streams or equivalent can be accomodated. If the space reserved is inadequate for your application, 
the system zone can be replaced with one constructed by your program. In addition, most procedures that 
create system objects have provision for an optional "zone" argument used for seizing space (see section 
4.5). 



33. Errors 

Whenever the system detects an error for which die user program has not supplied its own error routine, 
the call SysErr(p:i, crrCode, p2, p3, ...) is executed. The errCode is a number that identifies the error; the 
p's are parameters that add details. 

Normally, SysErr calls Swat (the debugger), which will print out an intelligible error message retrieved 
from the file Sys.Errors. The facilities of Swat (see "Alto Subsystems Manual") can dien be used to 
interrogate the program state more fully, and ultimately to continue or abort its execution, 

3.4. Streams 

The purpose of streams is to provide a standard interface between programs and their sources of sequential 
input and sinks for sequential output. A set of standard operations, defined for all streams, is sufficient for 
all ordinary input-output requirements. In addition, some streams may have special operations definedfor 
them. Programs which use any non-standard operations thereby forfeit complete compatibility. 

Streams transmit information in atomic units called items . Usually an item is a byte or a word, and this is 
the case for all the streams supplied by the operating system. Ofcourse, a stream supphed to aprogrmn 
must have die same ideas about the kind of items it handles as the program does, or confusion will result 
Normally, streams which transmit text use byte items, and those which transmit binary information use 
words. (The 16-bit quantity which Bcpl passes as an argument or receives as a result of a stream operation 
could be a pointer to some larger object such as a string, although the operating system implements no 
such streams. In this case, storage allocation conventions for the objects thus transmitted would have to be 
defined.) 

You are free to construct your own streams by setting up a suitable data structure (section 4.2) which 
provides links to your own procedures which implement the standard operations. 
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The standard operations on streams are (S is tlie stream; "error" means that Errors(S, ec) is executed, 
where ec is an error code): 



Gets(S) 
Puts(S, I) 

Resets(S) 
Putbacks(S, I) 

Endofs(S) 
Closes(S) 
Stateofs(S) 
Errors(S, ec) 



returns the next item. Some streams give an error if Endofs(S)is 
tiue before the call, and others just wait for the next item, 

writes 1 into the stream as the next item; error if the stream is 
read-only, if there is no more space or if tliere is some hardware 
problem. 

restores the stream to some initial state, generally as close as 
possible to the state it is in just after it is created. 

modifies S so that the next Gets(S) will return I and leave S in 
the state it was in before tlie Putbacks. Error if there is already a 
putback in force on S. (No streams provided by the operating 
system implement a Putbacks operation.) 

true if there are no more items to be gotten from S. Not defined 
for output streams. 

destroys S in an orderly way, and frees the space allocated for it. 
Note that this has nothing to do with deleting a disk file. 

returns a word of state information which is dependent on the 
type of stream. 

reports the occurrence of an error with error code ec on the 
stream. When a system stream is created, Errors is initialized to 
SysErr (see section 3.3), but the user can replace it with his own 
error routine. 



Streams are created differendy depending on the device being accessed (disk, display, keyboard, or 
memory). The procedures for creating streams are described below. 



3.4.1. Disk streams 

The system distinguishes four kinds of object which have something to do with storing data on the disk: 



Disk Pack: 



Disk file: 



File directory: 



Disk stream: 



A storage medium that is capable of storing data in various 
pages. Most operating system functions default the choice of 
disK to "sysDisk", a structure which describes drive of a Diablo 
model 31 cartridge, 

A vector of bytes of data held on some disk, organized into pases 
for some purposes, A file exists only on the disk (except that 
parts of it may be in memory if an output stream is associated 
with it) and is named by an 80-bit entity called a file pointer 
(FP), 

A disk file which contains a list of pairs <string name. FP>. 
Documentation on the format of the file can be found with the 
BFS package documentation contained in an appendix to this 
manual. 

Used by a program to transfer information to or from a disk file. 
A stream exists only in memory and is named by a pointer to a 
data structure. 
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The procedures that operate on disk streams are described in documentation for the "DiskStrcams" 
software package contamcd in an appendix to this manual. Below is a summary list of the functions (in 
addition to the generic functions described above): 

CreateDiskStream(filcPtr, type [ksl^peReadWrite], itemSize [wordltem]. Cleanup [Noop], errRtn 

[SysHrr], zone [sysZone], nil, disk [sysDisk]) = a disk stream, or 
if an error is encountered while mitializing the stream. filePtr 
is the sort of object stored in a file directory. Legal types are 
kslypeReadOnly, ksrypcReadWrite, and ksTypeWriteOnly. 
Legal item sizes arc wordltem and charltem. 

CleanupDiskStream(s) Flush any buffers to the disk. 

RcadBlock(s, address, count) = actualCount. Read up to count words from the stream into 

consecutive memory locations; return the actual number of 
words read. (Non-intuitive things happen at the end of a file 
with an odd number of bytes - read tlie documentation 
carefully) 

WriteBlock(s, address, count) Write count words from consecutive memory locations onto the 

stream. 

LnPageSize(s) ~ log (base 2) of the page size, in words, of the files manipulated 

by the stream. 

PositionPage(s, page) Posidons the file to byte of the specified page (page 1 is the 

first data page). 

PositionPtr(s, byteNo) Positions the file to the specified byte of the current page, 

FileLengdi(s, filePos []) ~ Lengdi. Returns number of bytes in file; positions stream to 

the last byte. 

FilePos(s, filePos []) == Pos. Returns die current byte posidon in die file. 

SetFilePos(s, filePos) or SetFilePos(s, HighOrder, LowOrder) Sets the position of the file to die 

specified byte. 

GctCurrentFa(s, filcAddress) Returns the current file address. 

JumpToFa(s, filcAddress) Posidons the file to the specified address (usually obtained from 

GetCurrentFa). 

GetCompleteFa(s, completeFileAddress) Returns a complete file address, including a 

filePtr. 

TruncateDiskStream(s) Truncates die file to the current position. 

ReadLeaderPage(s, address) Reads the 256-word leader page of the file into consecutive 

locations starting at address. 

WriteLeaderPage(s, address) Writes 256 words onto the leader page of the file. 

The operating system also contains a package for dealing with files at a lower level, the "Bfs" (Basic file 
system) package. 

Disk Errors: The system will repeat five times any disk operation which causes an error. On the lastdiree 
repeddons, it will do a restore operation on the disk first. If five repedtions do not result in an error- free 
operation, a (hard) disk error occurs; it is reported by a call on Errors for the stream involved. 
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3,4.2. Display streams 

Display streams arc implemented with the "DspStrcam" package, described in separate documentation 
contained in an appendix to this manual. Below is a list of the functions included (in addition to the 
generic stream functions): 



CreateDisplayStream(nLines, 



pBlock, iniock. Font [sysKont], wWidth [38], options 
[DScompactleft+DScompactrightj, zone [sysZonej) - a display 
stream. pBlock is the address of a region IBlock words long for 
the display bitmap. nLines is the number of text lines in die 
stream. 1his procedure does not commence displaying die 
stream text -- see ShowDisplayStream. 

ShowDisplayStream(s, how [DSbelow], otherStream [dsp]) This procedure controls the presentation 

of the stream on the screen. If how is DSbelow, the stream will 
be displayed immediately below otherStream; if DSabove, 
immediately above; if DSalone, the stream will become the only 
display stream displayed. If how is DSdelete, the stream s will 
be removed from the display. For DSalone and DSdelete, the 
third argument is needless* 



GctFont(s) 
SetFont(s, font) 
ResetLine(s) 

GctBitPos(s) 
SetBitPos(s, pos) 

GetLinePos(s) 

SetIinePos(s, pos) 

InvertLine(s, pos) 
EraseBits(s, nBits, flag [0]) 

GctLmarg(s); SetLmarg(s) 
GetRmarg(s); SetRmarg(s) 



Returns current font. 

Sets current font (use carefully - see documentation). 

Erases all infonnation on the current line and resets the position 
to the left margin. 

Returns the horizontal position of the stream. 

Sets the horizontal position on the current line (use carefully - 
see documentation). 

Returns the index of tiie line into which characters are presenUy 
being put. 

Sets the line number into which subsequent characters will be 
put. 

Inverts the black/white sense of the line given by pos. 

Erase bits moving forward (nBits>0) or backward (nBits<0) from 
the current position. Set to background if flag-0; to the 
complement of the background if flag:= 1; invert present values 
ifflag = "l. 

Get and set left margin for the current line. 

Get and set right margin for the current line. 



CharWidth(StreamOrFont, char) Get the width of the character, using tiie specified font or the 

current font in the specified stream. 

The "system display stream" is always open, and can be accessed by the system scalar "dsp." 
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3.4.3. Key board Streams 

llicre is a single keyboard stream in which characters are buffered. The stream is always open, and maybe 
accessed through the system scalar '^keys." The only non-null operations are Gets; Endofs, which is true if 
no characters arc waiting; and Resets, which clears the input buffer. 

1'hc keyboard handler periodically copies the mouse coordinates into the cursor coordinates, truncatingat 
the screen boundary. 'Ihis function is governed by the value of a cell referenced by @ IvCursorLink; if itis 
zero, the fimction is disabled. 

I.ow -levcl keyboard function s. Although the standard keyboard handler contains no facilities for detecting 
transitions"!)] keyset or mouse keys, a user function may be provided that will be called 60 times a second 
and can extract relevant information from a table passed to it. The call SetKeyboardProc(uKbProc, stack, 
stackLength) will install uKbProc as the user procedure; stack is a vector Uiat will be used for stack space 
when uKbProc is run (you must provide enough!). SetKcyboardProcO will reset the keyboard handler, 
and cease calling uKbProc. (Note: If Uie program has used the Junta procedure, the user keyboard 
procedure must be deactivated during a CounterJunta or finish unless all its state lies below 
OsFinishSafeAdr.) If active, every 16 milliseconds, the keyboard handler will execute uKbProc( tab), where 
tab points to a data structure denned by the KBTRANS structure (see the file SysDefs.d). Thelransition 
word is non-zero if a key transition has been detected; GoingUp or GoingDown tell which sort of 
transition has occurred; and Keylndcx gives the key number. KcyState is a 5-word table giving the stateof 
the keys after the transition has occurred: if a key with Keylndex~i is presently down, bit (i rem 16) of 
word div 16) will be 1. The entries CursorX and CursorY give the current location of the cursor. 

7'hc value returned by uKbProc determines subsequent processing. If true is returned, the operating 
system treats the key transition (if any) according to normal conventions, if false is returned, the operating 
system assumes that uKbProc has perfoimed whatever processing is intended, and the interrupt is simply 
dismissed. 

Keylndcx values are tabulated below. Keys are normally given by their lower-case marking on the key 
top; those with more than one character on their tops are specified by <name>. <X> are unused bits; 
<blank-top> is tlie key to the right of the <bs> key; <blank-middle> to the right of <return>; and<blank- 
bottom> to the right of <shift-right>. 

Values Keys 

0-15 546e7duv0k-p/\<lf> <bs> 

16-31 32wqsa9ixol,'] <blank-middle> <blank-top> 

32-45 1 <esc> <Uib> f <ctrl> c j b z <shiil-left> . ; <return> ^ <del> <X> 

48-63 r t g y h 8 n m <lock> <space> [ - <shift-right> <blank-bottom> <X> <X> 

64-71 unused 

72-76 Keyset keys in order, left = 72 ; right = 76 

77 RED (or left or top) mouse button 

78 BLUE (or right or bottom) mouse button 

79 YELLOW (or middle) mouse button 

As an aid to interpreting Keylndcx values, the system scalar kbTransitionTable points to a table, indexed 
by Keylndcx, that gives a KBKEY structure for the key; if it is zero, the operating system has no standard 
interpretation of the key, 

3.4.4. Fast Streams to Memory 

The operating system also contains procedures that allow very efficient stream I/O to memory blocks. 
These functions, described in the Streams package documentation, allow one for example to use much 
more memory buffering for disk transfers than nonnally allocated by the disk stream mechanism. 
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3.5. Directory Access 

Most user programs do not concern themselves with file pointers, but use system routines which godirectly 
from string names to streams. By a 'Tile name" we mean a string which can be converted mto a file 
identifier by looking it up in a directory. File names are arbitrary Bcpl strings which contain only upper 
and lower case letters, digits, and characters in the string " + -.!$". File names are stored in directories as 
they are typed, but no distinction is made between upper and lower case letters when they are looked up. 
Dots (".") arc used to separate file names into parts. If there is more than one part, the last part is called 
die extension , and is conventionally used much like extensions in Tenex. 

There is an optional version number facility. It is not available in the standard release of the operating 
system (NewOs.boot), but is available in an unsupported alternate version (NewOsV.boot). If the version 
number facility is enabled, the intcipretation of exclamation mark ("!") is special; if a file name ends with 
a ! followed only by digits, the digits specify the file version number. 

A lookup name , presented to one of the directory funcdons given below, is usually a file name. However, 
it may optTonaRy specify the name of a directory in which to look for the file (or record the new file). The 
lookup name is processed from left to right. If the character "<" appears at the head of the lookup name, 
the system directory ("SysDir.") becomes the "current" directory; whenever the character > follows a 
name, die name is looked up in the current directory and that file becomes the new current directory. ^ Ifno 
directory is specified in the lookup name, the "working directory" is assumed. Example: "<dir>fil. will 
look up dir in the system directory SysDir, and will then look up fil in dir. Any illegal characters ma 
lookup name are replaced with "-" characters. 

File Versions: The file system also supports multiple versions of the same file; this feature may be enabled 
or disabled when tlie operating system is installed, llie version number is recorded by appending an 
exclamation mark and the decimal version number to the file name; file names without version numbers 
appended act as if they are "version 0." The OpenFile function uses lookup names and version control 
infoimation to locate a desired file. If the lookup name contains a version number (e.g., Sys.hrrors!3. ;, 
Uien no version defaulting is donc-the lookup operates on precisely the file specified. (This processing is 
identical wiUi versions enabled and disabled.) 

If the lookup name does not specify a version number and file versions are enabled Uien the 
versionControl parameter specifies how defauUing is to be done (in the definitions, "oldest" refers to the 
file witli the "lowest" version number; "latest" refers to the file with the "highest" version number): 

verLatest The latest version is used. 

verLatestCreatc The latest version is used. If die file does not exist, it is created 

with version number (i.e., no number will be appended 
explicitly to the file name): Uiis is to prevent needless 
accumuladon of version numbers in system- related files (.e.g, 
.Run files). 

verOldest Tlie oldest version is used. 

verNew A new file will always be created. A system parameter, 

established when die system is installed, determines how many 
old versions will be preserved. If diat default should be 
overriden, just add the desired number of versions to verNew. 
e.g. a versionControl value of verNew +4 will create a new file 
and retain at most three older versions. 

This version option may reuse disk pages allocated for the oldest 
version of die file, but the serial number and file name will of 
course be changed. If (newest-oldest) + 1 is greater than or equal 
to the number of versions to keep, oldest is reused in this fashion 
to become version newest+1. For example, if verNew is 
specified, 2 versions are to be kept, and foo!2 and foo!3 exist, 
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verNcw will create the file foo!4 by remaking the old file foo!2. 
Note that this calculation does not verify that all versions 
between oldest and newest actually exist. 

If only one file matches the lookup name, and its version 
number is 0, the file is simply overwritten (like verLatestCreate); 
a new version is not created. 

If no files of the given name exist, version number of the file is 
created (i.e., no version number is explicitly attached to the file 
name). 'Ihe verNewMways option (below) can be used if 
version 1 should be created, 

verNcw Always Similar to verNew, but if no earlier version of the file exists, 

version 1 is created. 

If versions are not enabled, then exact matches are performed on the entire file name. Thus, if the file 
"Sys.Rrrors!2'* is present on a disk with versions disabled, tlie lookup name "Sys.Errors" will not match 
this file; the lookup name "Sys.Errors!2" will. The versionControl parameter is still relevant: if no file 
matchiM the lookup name is found, verLatcst and verOldest will not create a new file, whereas the other 
versionControls will. 

The following function creates a disk stream (see above) in conjunction with the Alto directory structure: 

OpenFile(lookupname, ksType [ksTypeReadWrite], itemSize [wordltem], versionControl [if 

ksType^kslypeReadOnly then verLatest else if 
ksType^ksTypeWriteOnly then verNew else verLatestCreate], 
hintFp [0], crrRtn [SysErr], zone [sysZone], nil, disk [sysDisk], 
CreateStream [CreateDisk Stream]) == a disk stream, open on the 
specified file, or if the open is unsuccessful for some reason, 
1 his routine parses the lookup name, searching directories as 
needed. After applying version control (e.g., making a new 
version), it calls CreatcStream(filePointer, ksType, itemSize, 
Noop, errRtn, zone, nil, disk), and returns the value of that call 

If hintFp is provided, it is assumed to be a file pointer (FP) that 
"hints" at the correct identification of the file. Before searching a 
directory, OpenFile will try using the hint to open the file, 
quickly returning a stream it the hint is valid (though no name or 
version checking is done). If the hint fails and lookupname is 
non-zero, the name will be parsed and looked up in the normal 
fashion. hintFp will be filled in with the correct file pointer. 
Note: If you wish to use standard file-lookup procedures, but to 
have the FP for die resulting file returned to you, zero the 
hintFp vector before calling OpenFile. In this case, tlie value of 
hintFp is not used in die lookup, but is filled in with the results. 



OpenFileFromFp(hintFp) 



OpenFile(0, 0, 0, 0, hintFp) 



DeleteFilc(lookupname, versionControl [verOldest], errRtn [SysErr], zone [sysZone] nil, disk 

[sysDisk]) = success. Deletes the file on the disk and removes 
the corresponding entry from the directory specified in 
lookupname. Returns "true" if a file was correctly found and 
deleted, otherwise "false." 

SetWorkingDir(name, fp, disk [sysDisk]) Sets the "current" directory for further lookups on the 

given disk. When the system is booted, the current directory is 
setto"<SysDir." 
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3.5.1. Low er-level directory Functions 

Several functions are provided for those who wish to deal with directories and file names at a lower level. 
The format of an Alto file directory is documented in the Disks documentation; definitions appear in 
AltoFileSys.d. 

ParseFilcName(dcstName, srcName, list, versionControl) - stream or 0. Strips leading directory 

information from srcName, puts the result in dcstName, 
appending a ".** if necessary, and returns a stream open on the 
directory in which the file should be looked up. hstIO = an 
errorRoutine, listll - a zone, list!3 ~ a disk which will be 
passed to OpenlMle along with versionControl when opening the 
directory stream. 

FindFdEntry(s, name, comparcFn [0], dv [], hd [|, versionControl [verLatest], extraSpace [0]) = a 

word pomtcr mto the stream s of a directory entry, or -I if no 
entry is located. If compareF^n is 0, normal comparison of file 
names and version control is performed; the result is a directory 
entry in dv, and a hole descriptor (hd) for a hole large enough to 
include the name, a new version numoer, and extraSpace words. 

Otherwise, compareFn is a user procedure that is invoked as 
each file name is read from the directory: compareF'n(name, 
nameRead, dvRcad). nameRead is the Bcpl name extracted from 
the directory; dvRcad is the dv extracted rrom the directory; and 
name is simply the second argument passed to FlndFaEntry 
(which need not be a string). If compareF'n returns false, the 
directory scan halts; the value of FindFdEntry is the byte 
position in tiie stream. If compareFn returns true, the search 
proceeds. 

Strategic note: If compareFn is TruePredicate, the directory is 
simply scanned in order to locate a hole large enough for 
extraSpace words. The result is saved in the hd hole descriptor, 
which may be passed to MakeNewFdEntry. 

In the standard release of the operating system (version 
numbering absent), the directory stream is left positioned at the 
matching directory entry if one was found and at the position 
described by hd otherwise. 

MakeNewFdEntry(s, name, dv, hd, extraStuff) makes a directory entry: dv is a pointer to a DV 

structure for the first part of the entry; name is a Bcpl string that 
is recorded after the entry (this string must be a legal internal file 
name, with the dot ".'* appended), and extraStuff is a pointer tea 
vector of additional stuff that will be entered following the 
name. The hd parameter is a pointer to a **hole descriptor" as 
returned from FindFdEntry. 

DeleteFdEntry(s, pos) Deletes the directory entry at byte location pos of the directory 

open on stream s. 

Strip Version(string) = version number. This function strips a version number, if 

any, from die end of the string argument, and returns the 
number (0 if no version specified). If, after stripping, there is no 
final "." on the string, one is appended. 

AppendVersion(string, version) Appends a version number and final "." to the string. 
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WriteDiskDescriptorO 
ReadDiskDescriptorO 



If changes have occurred, the copy of the disk descriptor for 
sysDisk tliat resides in memory is written onto the disk file 
"DiskDescriptor." 

This function restores the copy of the disk descriptor forsysDisk 
that resides in memory from the disk file *'DiskDescriptor/' 



3.6. Memory management 

Table 3.1 shows the layout of memory. Table 3.2 tells how to obtain the current values of the symbolic 
locations in Table 3.1. The free space (EndCode to StackEnd) can be manipulated as follows: 



returns a pointer to a block of nwords words, or if there isn*t 
enough room. It won*t leave less than 100 words for the stack to 
expand. 

frees a block provided by GetFixed. 

returns the size of the biggest block which GetFixed would be 
willing to return. 

resets endCode explicitly. It is better to do this only when 
endCode is being decreased. 

The allocator is not very bright, FreeFixed decrements endCode if the block being returned is 
immediately below the current endCode (it knows because GetFixed puts the length of the block in the 
word preceding the first word of the block it returns; please do not rely on this, however, since there is no 
guarantee that later allocators will use tlie same scheme). Otherwise it puts tlie block on a free hst. When 
another FreeF'ixed is done, any blocks on the free list wnich are now just below endCode will also be freed. 
However, the allocator makes no attempt to allocate blocks from the free list. 



GetFixed(nwords) 

FreeFixed(pointer) 
FixedLeftO 

SetEndCode(newValue) 



3.7. The Alloc allocator 

The operating system includes a copy of the Alloc package; documentation is contained in an appendix to 
this manual. 

InitializeZone(start, length, OutOfSpaceRoutine [...SysErr], MalFormedRoutine [...SysErr]) = a 

*'zone.'* These zones are compatible with the "zone ' arguments 
to operating system functions (e.g., sysZoneV Allowing 
MalFormedRoutine to default to SysErr causes a through check 
of the zone data structures to be performed each time a block is 
allocated or freed. To avoid tiiis (considerable) overhead, pass a 
zero for the MalFormedRoutine. The default sysZone nas a 
MalformedRoudne of SysErr. 

AddToZone(zone, block, length) Adds block to the zone, 

Allocate(zone, length, returnOnNoSpace [false], even [false]) = pointer to a block of length words 

allocated from zone. If even is true, the pointer is guaranteed to 
be a even number. 



Free(zone, ptr) 
CheckZone(zone) 



Returns the block pointed to by ptr to the zone. 
Performs a consistency check on the zone data structure. 
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3.8. The Basic File System 

A set of procedures for driving the disk hardware for Diablo Model 31 and 44 disk cartridges is included in 
the operating system. These functions are documented in the "Disks" documentation, appended to this 
manual. 

3.9. Objects 

It is often convenient to define an abstract object and its operations by a single entity in the Bcpllanguage. 
As the largest entity Bcpl can deal widi is a 16-bit number, we must use a pointer to a structure of some 
kind that defines both the procedures and data associated with the object. Streams, Zones and Disks are 
examples of such abstract objects. Such objects arc typically defined by a structure such as: 

structure ZN: 

Allocate word //Op 

Free word //Op 

Base word //Val 
Lengdi word //Val 
] 



where the Op's point to procedures and the Val's are data for the structure. A typical call on one of the 
abstract procedures is thus (zone»ZN.Allocatc)(zone, argl, arg2, arg3). The virtue of such an 
arrangement is that any structure diat simulates the effects of the procedures can pose as a Zone. 



In order to encourage the use of such objects, the operating system has very efficient implementations for 
this calling mechanism: 

CallO(s, a, b, ...) Does (s!0)(s, a, b, ...) 

Calll(s, a, b, ...) Does (s!l)(s, a, b. ..,) 

Call2, Call3, ..., CalllS analogously. 

Thus, the operating system defines Allocate = CallO, and Free = Calll, consistent with the Alloc package 
described above. Note for assembly-language programmers: the CallX functions actually enter the proper 
function at the second instruction, having already executed a STA 3 1,2 to save the return address. 

3.10. Miscellaneous 

This section describes a collection of miscellaneous useful routines: 

Wss(S, string) writes the string on stream S. 

Ws(string) writes the string on the system display stream, dsp. 

Wl(string) Ws(string), followed by a carriage return. 

Wns(S, n, nc [0], r[-10]) writes a number n to stream S, converting using radix abs(r). At 

least nc characters are delivered to the stream, using leading 
spaces if necessary. The number is printed in signed notation if 
r<0, in unsigned notation if r>0. 

Wos(S, n) writes an unsigned octal representation of n on stream S. 

Wo(n) writes an unsigned octal representation of n on the display 

stream. 
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TaiePredicateO 

FalsePredicateO 

NoopO 

Dvec(caller, nVl, nV2, ...) 



always returns -1. 

always returns 0. 

null operation; returns its first argument if any. 

this routine allocates "dynamic" vectors in the current frame, 
caller is the name of the procedure calling Dvec. The use of the 
routine is best given with an example: the routine ShowOff 
wants two vectors, VI and V2: 



let ShowOff(Vllengdi, V21ength) be 

let VI = Vllength 

let V2 = V21engtli 

]>ec(ShowOfn Iv VI, Iv V2) 

// now VI points to a block Vllength 4- 1 words long 

// and V2 points to a block V21ength + 1 words long 

Warning: any addresses that point into the stack frame of 
ShowOff before it is moved by the Dvec call will not be correct 
after the call. Thus, for example, a "let a = vec 10" before the 
call will cause the address in a to be useless after the call. 

DefaultArgs(lvNa, base, dvl, dv2, ) Utility procedure to fill in default arguments. IvNa points to 

the "numargs" variable in the procedure; abs(base) is the 
number of initial arguments that are not to be defaulted; thedvj 
are the default values (i<ll). If base<0, then an actual parameter 
of zero will cause the default to be installed; otherwise only 
(trailing) omitted parameters are defaulted. Thus: 

let Mine(how, siz, zone, errRtn; numargs n) be 

DefaultArgs(lv n, -1, 100, sysZone, SysErr) 

]" 

will default arguments siz, zone, errRtn if missing or zero to 100, 
sysZone and SysErr respectively. Note that Bcpl will allow j^ou 
to omit parameters in tlie middle of a parameter list by using 
"nil," but DefaultArgs has no way of knowing that you did this. 



MoveBlock(dest, src, count) 
SetBlock(dest, val, count) 
Zero(dest, count) 
BitBlt(bbt) 
Usc(a,b) 

Min(a, b), Max(a, b) 

Umin(a, b), Umax(a, b) 



Uses BLT: for i = to count- 1 do destii - src!i. 

Uses BLKS: for i = to count-1 do destii - val. 

Same as SetBlock(dest, 0, count). 

Executes the BITBLT instmction with bbt in AC2. 

Use performs an unsigned compare of a and b and returns -1 if 
a<b,Difa=b, lifa>b. 

Returns the minimum or maximum of two signed integers, 
which must differ by less than 2tl5.. 

Returns the minimum or maximum of two unsigned integers. 
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DoublcAdd(a, b) 

EnablelnterruptsO 
lOisablclnterruptsO 
StartlO(acO) 

IdleO 



Timcr(tv) 
ReadCalcndar(dv) 

SetCalendar(dv) 

EnumerateFp(proc) 
CallSwat(sl, s2) 



The parameters a and b each point to 2-word double-precision 
numbers. DoubleAdd docs a<-a + b. Note diat subtraction can 
be achieved by adding the two's complement; the two's 
complement is the one's complement (logical negation) plus 1. 

Enables Alto interiojpt system. 

Disables intcraipt system. Returns tme if interrupts were on. 

Executes the SIO emulator instruction with its argument in acO. 
Thus StartlO(v^ 100000) will boot the Alto if it has an Ethernet 
interface. 

This procedure is called whenever the operating system is 
waiting for something to happen (e.g., a keyboard character to be 
struck, or a disk transfer to complete). The static Ivldle points to 
the operating-system copy of the procedure variable so that 
programmers may install their own iale procedures by executing 
*^@rvldle = Myldle". 

Reads the 32-bit miUisecond timer into tv!0 and tv!L Returns 
tv!l as its value. 

Reads the current datc-and-time (32 bits, with a grain of 1 
second) into dv!0 and dv!l. Returns dv as its value. 
(Subroutines for converting date-and-time into more useflil 
rormats for human consumption are available. See subroutine 
package documentation, under lime.) 

Sets the current date-and-time from dv!0 and dv!l. (Normally it 
should not be necessary to do this, as the time is set when the 
operating system is booted and has an invalid time. Thereafter, 
the timer facilities in the operating system maintain the current 
time.) 

For every file pointer saved by the system (e.g., fpComCm, 
fpRemCm, etc.), call proc(fp). 

This flmction invokes an explicit "call" on Swat. Either of the 
arguments that appears to be a Bcpl string will be printed out by 
Swat 



3.10.1. Routines for Manipulating Bcpl Frames 

The following roudnes ease massaging Bcpl frames for various clever purposes such as coroutine linkages. 
See section 47 for a description of the data structures involved. 



FrameSize(proc) 

MyFrameO 

CaliersFrame(f) 

FramesCaller(f) 



Returns the size of the frame required by proc. 

Returns tlie address of the current frame. 

Returns the address of the frame that "called" the frame f (if fis 
omitted, tlie current frame is used). 

Returns the address to which the caller of frame f sent control, 
provided that he made the call with a normal instruction (jsrii, 
jsris). If error, returns 0. 
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CallFrame(f, a, b) 

GotoFramc(f, a, b) 
CoCall(a, b) 
CoReturn(a, b) 
RetLimTo(label) 
GotoIxibel(f, label, v) 

RetryCall(a, b) 



Return From(fnOrF'rame, v) 



Sends control to frame f and links it back to this one (i.e., when f 
returns, the CallFrame call returns), a and b are optional 
arguments. 

Like CallFrame, but does not plant a return link. 

CallFrame(CallersFrame(), a, b) 

Like CoCall, but does not plant return link. 

Returns to a given label in the frame of the caller. 

Sends control to the specified label in the specified frame, and 
passes V in AGO. 

Repeats the call which appears to have given control to the caller 
with a and b as the first 2 arguments, and the other arguments 
unchanged, 'fhere are certain ways of calling functions which 
cannot be retried properly. In particular, die address of the 
procedure must be the value or a static or local variable; it 
cannot be computed. Thus "a»proc(s, b)" cannot be retried, 
but *'let pr=a»proc; pr(s, b)" can be retried. 

Looks for a frame f which is either equal to fnOrFrame, or has 
FramcsCaller(f) equal to fnOrFrame. It then cuts back the stack 
to f and simulates a return from f with v as the value. If error, it 
returns 0. 



3.11, Subsystems and user programs 

All subsystems and user programs are stored as "Run files'*, which normally have extension ".Run". Such 
a file is generated by Bldr and is given the name of the first binary file, unless some other name isspecified 
for it. 1 he format of an Alto run file is discussed in section 4.8 and in the Bcpl manual. 

CallSubsys(S, pause [false], doReturn [false], userParams [0]) will read in a run file and send control to its 
starting address, where S is an open disk stream for the file, positioned at the beginning of the file. If pause 
is taie, then CallSwat("Pause to Swat"); Ctrl-P starts the program. (doReturn will never be implemented, 
but would have allowed a return to the caller after the called subsystem "finished.") userParams is a 

?ointer to a vector (length up to lUserParams) of parameters which will be passed to the called subystcm. 
he parameters are formatted according to conventions given in SysDefs.D (stmcture UPE): each 
parameter is preceded by a word that specifics its type and the length of the block of parameters; a zero 
word tenninates this list. When the Alto Executive invokes a program witii GallSubsys, it passes in 
userParams an entry with type globalSwitches which contains a list of ASCII values of global switches 
supplied after the program name. 

The open stream is used to load the program into Alto memory according to placement information 
included in the file. The stream is then closed; no other open streams are affected. 

The program is started by ^ call to its starting address, which will normally be the first procedure of the 
first file given to Bldr. This procedure is passed three arguments. The first is the 32 word layout vector for 
the program, described in the Bcpl manual. The second is a pointer to a vector of parameters provided by 
the caller (the userParams argument to CallSubsys). The third is the "complete file address" (CFA) for a 
particular point in the file that was used to load the program. If no overlays are recorded in the Run file, 
tills point is the end of file. If overlays are contained in the file, the CFA points to the first word of the first 
overlay section (this can be used as a hint in a call to OpenFile when loading overlays contained in the 
same file). 

Subsystems conventionally take their arguments from a file called Com.Cm, which contains a string which 
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normally is simply the contents of the command line which invoked the subsystem (see section 5). The 
subroutme package GP contains a iprocedurc to facilitate reading this string according to the conventions 
by which it is normally formatted. This is not a standard routine but must be loaded with your program. 
(P'or more information on GP, see the "Alto Software Packages Manual.") 

3.12. Finish -- Terminating Execution 

When a program teiminates operation, it "finishes," returns to die operating system and ultimately to the 
Executive. A program may finish in several ways: 



Bcpl return 

Bcpl finish 
Bcpl abort 
Swat abort 



OsFinish(fCode) 



If the main procedure in the user program (die one invoked by 
CallSubsys) ever returns, the program finishes. Equivalent to 
OsFinish(fcOK). 

If the "finish" construct is executed in a Bcpl program, it 
terminates. Equivalent to OsFinish(fcOK). 

If the "abort" construct is executed in a Bcpl program, it 
terminates. Equivalent to OsFinish(fcAbort). 

If, during program execution, the "left shift" key and the "Swat 
key" (lower-rightmost key on Alto I keyboards, upper-rightmost 
key on "ADL Alto II keyboards) are depressed concurrently, 
tlie program is aborted. Similarly, if the <control>K ("kill ') 
command is typed to Swat, the program is aborted. Both are 
equivalent to OsFinish(fcAbort). 

An explicit call to this function will also terminate execution. 
The value of fCode is saved in the static OsFinishCode, which 
may be examined by the Executive and die next program that it 
invokes. Values of fCode presendy defined are: fcOK=0; 
fcAbort=l. 



When a program finishes, the value of die finish code is first recorded. Then, if the value of the static 
UserFinishProc is non-zero, the call UserFlnishProc(OsFinishCodc) is performed before restoring the 
operating system state. This facility is useful for performing various clean-ups. (Note: To set 
UserFinishProc, it is necessary to execute ©IvUserFinishProc = value.) In order to permit independent 
software packages to provide for cleanups, the convention is that each inidalization procedure saves the 
present value of UserFinishProc and then replaces it with his procedure. This procedure will do the 
cleanups, restore UserFinishProc, and return: 

// Initialization procedure 

stiUic savedUFP 

savedUFP - @lvUserFinishProc 

©IvUserFinishProc - MyCleanUp 

// The cleanup procedure 
let MyCleanUp(code) be 

... cleanups here 

@lv UserFinishProc - savedUFP 

] 



Finally, control is returned to the operating system, which resets the interrupt system, updates the disk 
allocation table, and invokes the execudve anew. 
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3.13. Junta 

'Jliis section describes some procedur 
programs to run on the Alto, and yet 
program deactivate various operating 
code and data used to implement the 
"levels:" 

levBasic 



levBuffer 

levFilePointers 

levBcpl 
levStatics 

levBFSbase 

levBFSwrite 



IcvAUoc 

IcvStreams 
levScan 

levDirectory 

levKeyboard 
levDisplay 

levMain 



es and conventions tliat can be used to permit exceptionally large 
to return cleanly to the operating system. The basic idea is to let a 
system facilities, and thereby recover tlie memory devoted to tlie 
facilities. To this end, the system has been organized in a series of 



Basic resident, including parity interrupt processing, time-of-day 
maintenance, the resident interface to the Swat debugger, and 
die initial processing for OslMnish. hnportant system state is 
saved here: EventVector, Uscr^famc. UscrPassword. 
OsFinishCodc. (Approximate size: 1000 words. This portion of 
the operating system is guaranteed not to extend below address 
175000B.) 

The system keyboard buffer (see section 4.6). (Approximate size: 
100 words) 

File hints. This region contains "file pointers" for frequently 
referenced files. (Approximate size: 70 words) 

Bcpl rundmc routines. (Approximate size: 300 words) 

Storage for most of the system statics. (Approximate size: 300 
words) 

Basic file system "base" functions, miscellaneous routines. 
(Approximate size: 1500 words) 

Basic file system "write" functions, the disk descriptor (used to 
mark those pages on the disk which are alreaciy allocated), 
interface to the time-of-day clock. (Approximate size: 1850 
words) 

The Alloc storage allocation package. (Approximate size: 660 
words) 

Disk stream procedures. (Approximate size: 2400 words) 

Disk stream extension for overlapping disk transfers with 
computation. (Approximate size: 400 words) 

Directory management procedures. (Approximate size: 1400 
words) 

Standard keyboard handler. (Approximate size: 500 words) 

Display driver (aldiough the storage for the display bitmap and 
for the system font lie below). (Approximate size: 1600 words) 

The "Main" operating system code, including utilities, 
CallSubsys, and the Junta procedure. (Approximate size: 1000 
words) 

Below levMain, where the stack starts, the system free-storage 
pool is located. Here are kept stream data structures, the system 
Font, and the system display bitmap. (Approximate size: 6000 
words) 



Alto Operating System 



May 5, 1980 



19 



This table of levels corresponds to the order in which the objects are located in the Alto memory: levBasic 
is at the very top; the bottom of levMain is the highest location for the Bcpl stack. 

The "Junta" function is responsible for de-activating these levels, thereby permitting the space to be 
reclaimed. When a program that has called Junta is ready to finish, it calls OsFinish in the normal way. 
Osl^nish performs the "counter-junta/' reading in portions of the operating system from the boot fileand 
rebuilding the internal state of those levels that were previously de-activated, and then proceeds with the 
finish, calling the Executive, etc. 

During the counter-junta process (which takes about 1/2 second), the display and interrupt system can 
continue to be active, provided that the code and storage they use lies below the address that is the valueof 
OsFinishSafeAdr. This permits a token display to remain; also a keyboard handler can continue to sense 
key strokes and record characters in the system keyboard buffer. 

Junta(levNamc, Proc) This function, which may be called onlv once before a "finish" 

or CounterJunta is done, de-activates all levels below levName. 
Thus levName specifies the name of the last level you wish to 
retain. (Manifest constants for the level names are in SysDefs.d.) 
It then sets the stack to a point just below the retained level, and 
calls Proc(), which should not return. 

The stack present at the time Junta is called is destroyed. The 
recommended procedure for saving data across a call to Junta is 
to locate the data below EndCode. 

A Junta always destroys the system free-storage pool and does 
not re-create it. Thercmre, open streams, the system display and 
system font are all destroyed. 

It is the user's responsibility to take care not to call operating 
system procedures that lie in tlie region de-activatea by the 
Junta. If in doubt, consult the file Syslik, which documents the 
association between procedures and levels. 

Any of the methods for terminating execution (section 3.12) 
automatically restores the full operating system. 

This function restores all de-activated sections of the operating 
system, and then calls Proc. The program stack present when 
CounterJunta was called is desti'oyed. This function is provided 
for those programs tliat do not wish to return to the operating 
system with a "finish," but may wish to do other processing (e.g., 
Calls ubsys). 

After calling Junta, many programmers will wish to restore some of the facilities that the Junta destroys, 
such as a free storage zone, a display stream, etc. Below is an example of how to go about this. Note that 
some thought is required because the operating system keeps a separate copy of statics from those 
referenced in your program. Thus when the OS defaults the tliird argument of CreateDisplayStreamto 
sysFont, it uses the OS copy of sysFont, not the copy available to your program. 

Junta(levXXXXX, Proc) 



...finish... 
CounterJunta(Proc) 



letProcQbe 

//Make a new sysZone: 

let V ~ vec 7035 // You can make it any size 

V = InitializeZone(v, 7035) 

@lvSysZone = v // Patch the os's version of the static 
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sysZonc ~ v // Patch my program's version of the static 

//Read in the system font again: 

let s ~ OpenFilcFromF^p(fpSysFont) 

let 1 - FileLcngth(s)/2 

let f - Allocatc(sysZonc, 1) 

Rescts(s); ReadBIock(s, f, 1); Closes(s) 

sysFont = f+2 // Patch my program's version of the static 
// Note that because os's version is not patched, 
// I cannot call Ws or otherwise default dsp. 

//Make a display stream: 

dsp == CreateDisplayStream(6, Allocate(sysZone, 4000), 4000, sysFont) 

ShowDisplayStream(dsp, DSalone) 



3.14. Events 

The operating system reserves a small communication region in v^hich programs may record various things. 
The intended use for this region is the recording of events by one program that deserve attention by 
another. The Executive cooperates in invoking programs to deal with events posted in the communication 
region. 

Events are recorded sequentially in a table pointed to by the static EventVector. The total lengtli of the 
table, available as F>entVector!-l, must not be exceeded by any program generating events. Each event 
entry (stmcture EVM; sec SysDefs.d) contains a header that specifies the type and length of the entry 
(length is in words and includes header size); following the header comes type-specific data(eventData). 
A zero word terminates the event table. 



At present, events are defined for: 
eventBooted 
eventAboutToDie 

eventlnstall 

eventRFC 

eventCallSubsys 



eventlnLd 



The operating system has just been booted. 

The operating system is about to be flushed, probably to run a 
diagnostic. 

The operating system is to be re-installed. (This event need only 
be used by the Executive "Install" command.) 

A Request For Connection packet arrived. The event data is: 
Connection ID (2 words), RFC Destination Port (3 words), RFC 
Source Port (3 words) and Connection Port (3 words). 

When the next "finish" occurs, the system will try to execute the 
file whose name is given as a Bcpl string in the eventData block. 
If the eventData block has length 0, the system will invoke the 
copy of Ftp that is squirreled away inside Sys.Boot. Because a 
"finish" is perfonned right after the system is bootstrapped, it is 
possible to InLd Sys.Boot with a message that contains an 
eventCallSubsys, and thereby to invoke an arbitrary program. 
See the next section for a description of InLd. 

Whenever the next "finish" occurs, the system will call 
InLd(eventData, eventData). This suggests that the first words 
of event data should be an FPRD for a file you wish to InLd. 
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If a program that generates an event has destroyed the event communication region, it is still possible to 
pass the event to the operating system. For example, if the memory diagnostic is amning and an Ethernet 
connection request arrives, die mechanism can be used to load the operating system and pass Uie 
eventRFC message to it. I'he mechanism is described in tlic next secdon. 



3.15. OutLd, InLd, ItootProm 

Three ftinctions are provided for dealing witii "OutFd" files that record the endre state of the Alto 
machine. When the operating system is loaded with the "boot" button, such a file restores the machine 
state cxacdy as it was at the time of the Installation of the operating system. The Swat debugger also uses 
these facilities, saving the entire machine state on the file "Swatee" when a break is encountered, and 
restoring the Swat debugger state from the file "Swat." 

In the discussion that follows, an FPRD stmcture is like a file pointer (FP), but the disk address is the Real 
disk address of the first page of Data in the file. 

OutLd(FPRD, OutLdMessage) Saves the state of the machine on the file described by FPRD, 

which must exist and be at least 255 data pages long. Note that 
the state saved includes a PC inside OutLd. OutLd returns 
after writing the file. Unless you know what you are doing, 
interrupts should be off when calling OutLd (otherwise, OutLd 
may save some parts of the machine state, such as the 
Activelntcrmpts word, that was perdnent to an interrupt in 
progress!). 

Programmers should be warned to think carefully about the state 
that is being saved in an OutLd. F^or example, die operating 
system normally saves in memory some state associated with the 
default disk, sysDisk. If OutLd saves this state on a file, and the 
program is later resumed widi InLd, the state will be incorrect. 
To be safe, state should be written out before calling OutLd fi.e., 
WriteDiskDescriptorQ), and restored when OutLd returns (i.e., 
ReadDiskDescriptor()). 



InLd(FPRD, InLdMessage) 



Copies the InLdMessage (length llnLdMessage) to a 
momentarily safe place and restores the machine state from the 
file described by FPRD, which must have been created by 
OutLd. Because the PC was in OutLd, OutLd again "returns, * 
but diis time widi the value 1, and the InLdMessage has been 
copied into the OutLdMessage. Note: OutLd returns with 
interrupts disabled in diis case. 

If the operadng system boot file is InLd'ed, die message is 
assumed to be a legal data structure for the EventVector, and is. 
copied diere. 

This function "boots" die Alto from die specified file. If it is 
apphed to a file written by OutLd, the state of the machine is 
restored and OutLd "returns" 2 with interaipts disabled. (Note: 
The effect of this funcdon differs from die effect of depressing 
die "boot" button. Unlike die boot button, the function in no 
way initializes the internal state of the Alto processor.) 

Some programs (e.g., DMT) will need to know how to simulate InLd or BootFrom: 

L Turn off the display and disable interrupts. 

2. Read the first data page of the boot file into memory locations 1, 2, ...#400. If you are loading 
die installed operating system, the first data page of the boot file is at real disk address 0. 

3. Store the label block for the page just read into locations #402, #403, ...#41L 



BootFrom(FPRD) 
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4. (This step applies only if simulating Inlxl.) Now let msa~rv 2. This points to a location where 
a brief message can be stored. Set msa!0:=: 1. Then for i:==0 to lInLaMessagc-1 domsa!(i-hl) 
= PrototypcBventVectorli. 

5. Jump to location 3, never to return. 



4. Data structures 

This section describes the data structures used by the operating system that may be required by users. 

4.1. Reserved Memory Locations 

The Alto Hardware Manual describes addresses reserved for various purposes. The file AltoDcfs.d 
distributed with the OS declares most of these as manifest constants. 

4.2. Streams 

The standard data structures for streams are given in the DiskStreams package file "Strcams.d", 
Documentation for the streams package includes a description. 

4.3. Disk files 

The structure of the Alto file system is described in documentation for the Alto file system (Disks). This 
includes a description of files, disk formats, directory fomnats, and the format of the disk descriptor. Bcpl 
declarations for these objects may be found in the file AltoFileSys.d. 

4.4. Display 

The data stRictures used to drive the Alto display are described in the Alto Hardware Manual. The font 
format for the Alto (.AL format) is also described there. Note that a font pointer such as the one passed to 
CreateDisplay Stream points to the tliird word of an AL font. 

4.5. Zones 

A program that wishes to create an operating-system object and retain control over the allocation ofstorage 
to the object may pass a "zone" to the operating system function that needs space (e.g.,CreateDiskStreani), 
A zone is simply a pointer "zone" to a structure ZN (sec SysDefs.d), with zone»ZN. Allocate containing 
the address of the allocation procedure (called by (zone»ZN.Allocate)(zone, lengthRequested)) and 
zone»ZN.Free containing the address of the free procedure (called by (zone»ZN.Free)(zone, block)). 
The zones created by the Alloc allocator package obey these conventions. 

The zone provided by the operating system is saved in the static sysZone. The user may replace the system 
zone by executing ©IvSysZone == value. Subsequent free-storage requirements for the operating system 
will be addressed to this zone. The system zone is restored when the user program terminates. Warning: 
The operating system keeps various (and undocumented) information in the system zone, and is unwilling 
to have the zone changed out from under it. The normal use of IvSysZone is to change the value of 
sysZone immediately after a call to Junta (which clears away sysZone). If you wish to create disk streams 
and preserve them across a call to Junta, pass your own zone as an argument to OpenFile. 
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4.6. Operating System Status Information 

A good deal cf informadon is retained in memory that describes the state of the Alto. Much of diis 
information is of relevance to programmers, and is contained in some static scalars: 



OsVersion 

OsVersionCompatible 
UserName 

UserPassword 

SerialNumber 

AltoVersion 
sysDisk 



IvSysErr 



IvParitySweepCount 
IvParityPhantomEnable 



The version number of die operating system. This number is 
incremented with each new release of the operating system, 
incorporating changes however minor. 

The lowest operating system version number believed to be 
compatible with the present system. 

This static points to a Bcpl-format string diat is the user's last 
name. It is initialized when the operating system is installed on 
die disk. The maximum length Cm words) that the UserName 
may occupy is recorded in UserName!-!. 

This static points to a Bcpl-format string that is die user's 
password, typed to the Executive Logm command. The 
maximum length (in words) tiiat die UserPassword may occupy 
is recorded in UserPasswordl-l. 

The serial number of die Alto you are on. This static has proved 
troublesome, because it is easy to forget that this too will be 
saved by OutLd, and can confuse Ethernet code when it 
suddenly springs to life monUis later on a different host halfway 
around the world. Its use is discouraged. 

This static contains the result of executing the VERS instruction. 
This static has proven troublesome for the same reasons as 
SerialNumber. Its use is discouraged. 

A pointer to the DSK structure, described in Disks.d, which 
describes die "disk" to be used for standard operating system 
use. This stmcture is actually of the format BFSDSK, and 
contains a copy of the DiskDescriptor data structure. The static 
diskKd points to this structure alone (structure KD; see 
AltoFileSys.d). The storage for sysDisk is in levBFS write; if you 
Junta to levBFSbase, you will need to manufacture a new 
sysDisk structure, by loading and calling BFSInit in your own 
program. 

This static points to die operating-system copy of die static tiiat 
contains die address of the error procedure. If you wish to 
replace SysErr, it suffices to say @lvSysErr== Replacement. 
Note that some procedures may have already copied the value of 
SysErr (e.g., when a stream is created, die value of SysErr is 
copied into die ST.error field in most cases). 

This static contains die address of die highest memory location 
examined when sweeping memory looking for parity errors. If 
no parity checking is desired, set ©IvParitySweepCount = 0. 

Tills static points to a flag diat determines whedier phantom 
parity errors will invoke Swat (a phantom parity error results 
from a parity interrupt that can find no bad locations in 
memory). ©IvParityPhantomEnable = will disable phantom 
reporting. 
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ErrorLogAddress 
ClockSecond 



File Hints 



Keyboard Buffer 



OsBuffer»OsBUF.First 
OsBuffer»OsBUF.Last 
OsBuffer»OsBUF.In 
OsBuffer»OsBUF.Out 



This static points to a network address of a spot where error 
reports (for such things as parity errors) should be sent, llie 
structure is a "port," as defined in Pup documentation. 

This static points to a double-precision integer that gives the 
count of number of RCLK ticks (when RCLK is viewed as 
returning a 32-bit number) in a second. This number is used for 
keeping time, and is nominally 1680000. If timekeeping is 
extremely critical, you may wish to calibrate your Alto and 
change this number. 

The operating system maintains file pointers for several 
commonly-used files. Using these hints in conjunction with 
OpenFile will substantially speed the process of opening 
streams, l^he files and file pointers are: 



SysDir 

SysBoot 

DiskDcscriptor 

User.Cm 

Com.Cm 

Rem .Cm 

Executive.Run 

SysFont.Al 



fpSysDir 

mSysBoot 

fpDiskDescriptor 

fpUserCm 

mComCm 

foRcmCm 

(pExecutive 

fpSysFont 



Although the system keyboard buffer is normally managed by 
the keyboard handler provided in the system, some programs 
may want to operate on it themselves. The most important 
instance of this is when a program that has done a Junta is 
finishing: if the program keeps its keyboard handler enabled, 
any characters typed during the counter-junta can still be 
recorded in the system buffer, and thus detected by the first 
program to run (usually the Executive). 

The static OsBufifer points to a structure OsBUF (see SysDeft.d) 
diat controls access to the buffer: 

First address of the ring buffer 
Last address of the ring buffer+ 1 
"Input" pointer (place to put next item) 
"Output pointer (place to take next item) 

The following code can be executed with interrupts on or off to 
deal with the buffer: 



GetltemO = valof //Returns if none there! 

if OsBuffer»OsBUF.In ea OsBuffer»OsBUF.Out then resultis 

letnewOut = OsBuffer»OsBUF.Out+l ^ ^ ^^ ^^ xv.^t.ttt^c- . 

ifnewOuteqOsBuffer»OsBUF.LastthennewOut == OsBuffer»OsBUF.First 

let result ^ @(OsBuffer»OsBUROut) 

OsBuffer»OsBUF.Out = newOut 

resultis result 

] 

Putltem(i) = valof //Returns if buffer full already 

lctnewIn = OsBuffer»OsBUF.In + l w^nTTiri^- . 

ifnewIneqOsBuffer»OsBUF.LastthennewIn = OsBuffcr»OsBUF.First 
if newin eq OsBuffer»OsBUF.Out then resultis 
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(S?(OsBuffcr»OsBUF.In) = i 
dsHuffer»OsBUF.In = ncwln 
resultis -1 
] 

GetlteinCountO - valof //Returns count of items in buffer 

letc =:: OsBuffer»OsBUF.In-OsBuffcr»OsBUF.Out 

ifc Is then c = c + OsBuffer»OsBUF.Last-OsBuffer»OsBUF.First 

resultis c 

] 

ResetltemBuffcrO be //Set buffer to empty 

OsBuffer»OsBUF.In = OsBuffer»OsBUF.First 
OsBuffer»OsBUF.Out = OsBuffer»OsBUF.First 
] 

#176777 This location, the last in memory, points to the beginning of the 

area used to save statics for levBasic through levBcpl. The file 
Sys.Bk documents offsets from this number where the various 
statics will be found. 

4J. Swat 

The operating system contains an interface to the Swat debugger (described in the "Alto Subsystems" 
manual). This interface uses OutLd to save the state of the machine on the file "Swatee," and InLdto 
restore the state of the machine from the file "Swat," which contains the saved state of the debugger itself, 
llie inverse process is used to proceed from an interrupt or breakpoint. Two aspects of the Swatinterface 
are of interest to programmers: 

IvAbortFlag If @lvAbortFlag is zero, holding down the <left-shift> and <B3> 

keys will simulate the call OsFmish(fcAbort), thus terminating 
execution of the running program. In critical sections, setting 
©IvAbortFlag to a non-zero value will disable aborts. The 
standard convention is to increment ©IvAbortFlag when 
entering such a section and to decrement it when exiting. This 
permits separate software modules to use the feature 
concurrently. 

IvSwatContextProc Although Swat saves and restores the state of the standard Alto 

I/O devices, it has no way to know about special devices 
attached to the machine. The programmer may arrange that a 
pcice of code will be called whenever Swat is trying to turn off 
I/O preparatory to calling OutLd, or trying to restart I/O after 
anInLd. Iftheprogrammer does 

©IvSwatContextProc = DLSProc, Swat will execute DLSProc(O) 
when turning off I/O, and DLSProc(-l) when turning it on. 
Since Swat can be invoked at any time, the Swat context 
procedure must be written in machine language and must not 
assume anything about the state of the machme or any data 
structures (in particular the Bcpl stack may be in an inconsistant 
state). 
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4.8. The Bcpl stack 

The Bcpl compiler detennines the format of a frame and the calling convention. The strategy for allocating 
stack frames, however, is determined by the operating system. We begin by describing the compiler 
conventions, which are useful to know for writing machine-language routines. 

A procedure call: p(al, a2, ...), is implemented in the following way. The first two actual arguments are 
put into ACO and ACl (AC2 always contains the address of the current frame, except during a call or 
return). If tliere are exactly three actual arguments, the third is put into F.cxtraArguments. If there are 
more than three, the frame-relative address of a vector of their values is put there (except for tlie first two), 
so that the value of the i-tli argument (counting from 1) is frame»F.extraArguments!(frameH-i). Oncethe 
arguments arc set up, code to transfer control is generated which puts the old PC into ACS and sets the PC 
to p. At this point, AC3!0 will be the number of actual arguments, and the PC should be set to AC3 + lto 
return control to the point following the call. 

A procedure declaration: let p(fl, f2, ...) be ..., declares p as a static whose value after loading will be the 
address of the instruction to which control goes when.p is called. The first four instructions of aprocedure 
have a standard form: 

STA 3 1,2 ; AC2»F.savedPC ^ AC3 

JSR ©GETFRAME 

<number of words needed for this procedure's frame> 
JSR (gS TOREARGS 

The Bcpl runtime routine GETFRAME allocates storage for the new frame, NF, saves AC2 in 
NF»F.callersFrame field, sets AC2 to NF, and stores the values of ACO and ACl (the first two 
arguments) at NF»F.formals tO and 1. If there are exactly three actual arguments, it stores the third one 
also, at NF»F.formals t2. Then, if tliere are three or fewer actual arguments, it returns to L+ 3, otherwise 
it returns to L+2 with the address of the vector of extra arguments in ACl; at tliis point a JSR 
©STOREARGS will copy the rest of the arguments. In both cases, the number of actual arguments is in 
ACO, and this is still taie after a call of STOREARGS. A Bcpl procedure returns, with the result, if any, in 
ACO, by doing: 

JMP ©RETURN 

to a runtime routine which simply does: 

LD A 2 0,2 ; AC2 ^ AC2»F.callersFrame 

LDA 3 1,2 ; PC*- AC2»F.savedPC4- 1 

JMP 1,3 

The information above is a (hopefully) complete description of the interface between a Bcpl routine and 
tiie outside world (except for some aaditional runtime stuff which is supplied by the operating system). 
Note that it is OK to use the caller's F.Temp and F.cxtraArguments in a machine-language routme which 
doesn't get its own frame, and of course it is OK to save the PC in the caller's F.savedPC. 

The operating system currently allocates stack space contiguously and grows the stack down. To allocatea 
new frame of size S, it simply computes NF= AC2-S-2 and checks to sec whether NF > EndCode. If not, 
there is a fatal error (Swat breakpoint at finish + 1)- if so, NF becomes the new frame. (Note: the "-2" in 
the computation is an unfortunate historical artifact.) 

4.9. Run files 

The format of a file produced by Bldr to be executed by CallSubsys is described by the stnicture definition 
SV in BCPLFiles.d. Consult tiie Bcpl manual (section on Loading) for interpretations of the various fields 
and the handling of overlays. 
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5. The Executive 

The Alto Executive is itself a subsystem and lives on the file Executivc.Run; if you don't like it, you can 
write your own. It is currently invoked from scratch after the operating system is booted, and whenever a 
subsystem returns. The Executive is fully documented in die "Alto Subsystems" manual. 

6. Operadnfi Procedures 

6.1. Installing die opcradng system 

The "Install" command causes the operating system to execute special code which completely initializes 
die system. The options of die install procedure are controlled by prompts. Installation is needed: 




will ask you several questions which determine it's confmuradon on your disk ("SysGen", if you 
will parden the expression) and finally the Executive will be invoked. The newly configured OS 
writes itself on the file Sys.boot, so you can delete NewOS.boot after installing. 

- When you wish to ERASE a disk completely and re-inidalize it. Tliis option pauses to let you 

insert the disk pack you want initiaUzed. This "new disk" function is invoked by answering 
affirmadvcly the quesdon "Do vou want to ERASE a disk before installing?" after answering 
affirmatively that you want the Long installation dialogue". See also the NEWDISK secdonoT 
the Alto Subsystems Manual. 

- When you wish to change die "user name" or "disk name" parameters of die operating system. 

The install procedure will prompt for these strings. It is also possible to specify a disk password 
diat will be checked whenever the operating system is booted, 

- When you wish to enable die "multiple version" feature of die file system. (Because few programs 

presently cope widi all the subdeties of diis feature, it is wise to leave it disabled.) 

- When you wish to extend a file system. Basic disks are often kept on Interim File Systems fi-om 

which users can copy them with CopyDisk. They are usually configured for a single Diablo 
model 31 disk. If your machine has more disk space, you can extend the file system by answering 
"Yes" to die question "Do you want to extend diis file system?" (diis is also part of die "long 
installation didog"). 

6.2. How to get out of trouble 

It occasionally happens diat a disk will not boot, or somediing runs awry during the booting process. In 
this case, the following steps should be considered: 

1. Run the Scavenger. This can be done in two ways: 

Place a good disk in the Alto, and invoke die Scavenger. When it asks if you wish to change 
disks, respond affirmatively, put the damaged disk m die machine and proceed when die 
drive becomes ready. 

If you have network access to a "boot server", hold down die <BS> and <'> keys and push die 
boot button. Continue to hold down <*> until a tiny square appears in die middle of die 
screen. You should now be talking to the Network Executive : type Scavenger<cr>. 
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When the Scavenger finishes, the attempt to invoke the Executive may fail because Scavenger was 
invoked from another disk. Try booting. If unsuccessful, go on to step 2. 

2. Use Ftp to get fresh copies of SysFont.al and Executive.Run. Again, this can be done in two ways: 

Place a good disk in the machine and invoke Ftp. After it is initialized, change disks, wait for 
the damaged one to become ready, and type tlie necessary Ftp commands to retrieve the files. 

Invoke Ftp via the Network Executive as in step 1. 

Now try booting. If unsuccessful, go to step 3. 

3. Install the OS. You guessed it; this can be done in two ways: 

Place a good disk in tlic Alto and type "Install." When asked for your name, place the 
damaged disk in the machine, wait for the drive to become ready, and proceed. 

Invoke the "NewOS" via the Network Executive. You will be asked: "Do you want to 
INSTALL this operating system?" 

6.3. Hie Name Conventions 

Various conventions have been established for Alto file names. The conventions are intended to be 
helpful, not authorative. 

1. All files relating to a subsystem "Whiz" should have file names of the form "Whiz.xxx", i.e. typing 
"Whiz.*" to the Executive should list them all, delete them all, etc. Example: Bcpl.Run, Bcpl.Syms, etc. 

2. File extensions are of preference chosen to be language extensions, i.e. they specify the language in 
which they are written. The present set is: 

Bcpl Bcpl source code 

Mu Micro-code source 

Asm Assembler source code 

Mesa Mesa source code 

Help A help file for the system given in the name 

Cm A command file for the Alto Executive 

3. File extensions are otherwise chosen to reflect the format of the file. The present set is: 

Bravo Text file with Bravo format codes 

Run Executable file produced by Bldr 

Image Executable file produced by Mesa 

Al Alto format font file 

Boot A file that can be booted 

Br Bcpl relocatable binary file 

Syms Bldr symbol table output 

BCD Mesa object code 

Dm File produced by the Dump command, 

read by the Load command 

Ts Text file containing a transcript 

Disk disk image CopyDisk format 
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6A. Miscellaneous information 

The key in the lower right corner of the keyboard on a Microswitch keyboard (<blank-bottom>) or in the 
upper right on an ADL keyboard (FRl) is called the Swat key. If you press it, as well as the <ctrl>and 
<lcft-shift> keys, the Swat debugger will be invoked. If you do this by mistake, <ctrl>P will resume your 
program without interfering with its execution, and <ctrl>K will abort your program. 

You can force an abort at any time by depressing the Swat key together with the <left-shift> key. 

In order for the operating system to run properly, the following files should be on your disk (those marked 
* are optional): 

SysDir System directory. 

DiskDcscriptor Disk allocation table. 

SysFontAl System display font. 

Executive.Run Executive (command processor). 

Sys.Boot Boot-file containing the operating system. 

Sys.Errors * Error messages file. 

Swat * Debugger program, created by running InstallSwat. 

Swatee Debuggmg rile essential to Swat. 

(Note: If you wish to change the font used by the operating system, it suffices to copy a new font to 
SysFontAl and boot the system.) 

If you intend to write programs that use the operating system facilities, you will want some additional files: 

Sys.Bk Required by Bldr to load programs that reference operating 

system functions. This file also shows which functions are 
implemented in which levels and the names of source files for 
the code. 

SysDefs.d Definitions of standard system objects. You will probably want 

to "get" this file in Bcpl compilations that use operating system 
functions extensively. 

Streams.d Data structure definitions relating to streams. 

AltoFileSys.d Data structure definitions relating to files. 

Disks.d * Data structure definitions relating to the "disk" object. 

AltoDcfs.d Definitions of places and things peculiar to an Alto. 

BcplFiles.d * Definitions of the formats of Bcpl-related files. 
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Name 



Opcode Address Function 



CYCEE 

JSRII 

JSRIS 

CONVERT 

DIR 

EIR 

BRI 

RCLK 


60000 
64400 
65000 
67000 
61000 
61001 
61002 
61003 


C 
D 
D 
D 


SIC 
BLT 


61004 
61005 


- 


BLKS 


61006 


- 


SIT 


61007 


- 


JMPRAM 
RDRAM 


61010 
61011 


- 


WRTRAM 

DIRS 

VERS 


61012 
61013 
61014 


- 


DREAD 

DWRITE 

DEXCH 


61015 
61016 
61017 


„ 


MUL 
DIV 


61020 
61021 


- 



BITBLT 



61024 



AGO*- AGO ley (if G ne then G else AGl); smashes AGl 

AG3 ^ PG + 1 ; PG ^ rv (rv (PG + D)) 

AGS ^ PG 4- 1 ; PG <- rv (rv ( AG2 + D)) 

character scan conversion 

disable interrupts 

enable interrupts 

PG<-interruptedPG;EIR 

AG0^16 msb of clock (from realTimeGlock); AGl^ 10 Isb of clock* 

#100 + 6 bits of garbage; resolution is 38.08 us, 

start I/O 

Block transfer of -AG3 words; AGO -address of first source v^ord-1; 

AGl = address of last destination word; AGO and AG3 are updated 

during the instruction 

Block store of -AG3 words; AGO = data to be stored; AGl = address 

of last destination word; AC3 is updated during the instruction 

start interval timer. For an interrupt when the time is 

timerlnteraiptTime, AGO should be 1 when this instruction is 

executed 

Emulator microcode PG*-AG1 in control RAM 

AGO^(if AC1[4] then RAM else R0M)!AG1 (left half if AG1[5], 

right half otherwise) 

RAM!AG1^(AG0,AG3) 

* Disable intermpts and skip if interrupts were on 

* AGO ^ (f En§ineeringNumber-l)*16 
+ Microcode Version 
** AG0<-rv(AG3); AGl^rv(AG3 xor 1) 
** rv(AG3)^AG0; rv(AG3-Hl)*-AGl 

** t*-rv(AG3); rv(AG3)^AG0; AGO^t; t^rv(AG3 + l); 

rv(AG3 + l)*-ACl;AGl^t 

Same as NOVA MUL: AG0,1^AG2*AGH- AGO 

Similar to NOVA DIV: AG1*-AG0,1/AG2; AGO has remainder. 

DIV (unlike NOVA version) skips the next instruction if no overflow 

occurs. 

* character scan conversion of bit-map manipulation 



+ BuildNumber)*256 



Notes: Address: G = bits 12-15; D = bits8-15; -==no address 

variables in function descriptions arc machine registers or page 1 locations 
* indicates available only in "new" microcode (SIO leaves ACO[0] = 0) 
** indicates available only on Alto II 



Table 2.1: New instnictions in Alto emulator 
(see Alto Hardware Manual for more details) 
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Device 


Diablo 31 


Diablo 44 




Number of drives/ Alto 


lor2 


1 




Number of packs 


1 removable 


1 removable 
1 fixed 




Number of cylinders 


203 


406 




Tracks/cylinder/pack 


2 


2 




Sectors/track 


12 


12 




Words/sector 


2 header 
8 label 
256 data 


same 




Data words/track 


3072 


3072 




Sectors/pack 


4872 


9744 




Rotation time 


40 


25 


ms 


Seek time (approx.) 


15 + 8.6*sqrt(dt) 


8-f3*sqrt(dt) 


ms 


min-avg-max 


15-70-135 


8-30-68 


ms 


Average access 


80 


32 (both packs) 


ms 


to 1 megabyte 








Transfer rates: 








peak-avg 


1.6-1.22 


2.5-1.9 


MHz 


peak-avg 


10.2-13 


6.7-8 


us-word 


]3er sector 
br full display 


3.3 


2.1 


ms 


.46 


.27 


sec 


for big memory 


1.03 


.6 


sec 


whole drive 


19.3 


44 (both packs) 


sec 



Table 2.2: Properties of Alto disks 
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LastMemLoc 

StartSystem 

StackBase 

StackEnd 

EndCode 



StartCodeArea 

400-777 

300-377 

20-277 

0-17 



Last memory location 

Base of system 

Root of stack; stack extends downward from here 

Top of stack, which grows down 

End of user program + 1 

This space contains user code and statics, loaded as specified by the 
arguments to Bldr. Default is to start at StartCodeArea and load 
statics into the first 400 words, and code starting at 
StartCodeArea 4-400. See Bcpl manual. 

Start of user program area 

Page 1: machine-dependent stuff (see Alto Hardware Manual) 

Bcpl mntime page 

User page 

Unused 



Table 3.1: Memory layout (all numbers octal); see section 3.6 



LastMcmLoc 
StackEnd 



EndCode 
StartCodeArea 



The operating system described in this document runs on 64K 

Altos; tliis location is 176777. 

The address of the frame in which the current procedure is 

executing is computed by the MyFrame procedure; alternatively, 

compute Iv (first argument of current procedure) -4 

Rv(335) 

User code may start at any address > 777. 



Table 3.2: Values of symbolic locations in Table 3.1 
(all numbers octal) 
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Operating System Change History 



This file contains an inverse chronological listing of changes to the Alto operating system. 

The "normal way" to install a new operating system is to retrieve a copy of the files NewOS.Boot, 
Sys.Syms, Sys.Errors and Sys.Bk that are being distributed. Say "Install NewOS.boot" to the Exec,answer 
the configuration questions and then delete NewOs.Boot. 

Version 19/16 - December 15, 1980 

Additions: The major addition is that you can now erase a disk and format it to use 14 sectors percylinder 
on DOs and Dorados. It is not possible to extend a 12 sector file system to 14 sectors "in place '; you must 
save your files, erase the disk and restore them. 

Changes: [BKSInit] The OS rcfijscs to boot when only one disk of a double disk file system is spinning. It 
can also detect certain other blunders like DPI containing a single disk file system rather than the second 
half of the filesystem starting on DPO. It is not possible to detect all bad cases. [KeyStreams] the static 
kbTransitionTable is not exported to users who wish to modify the OS's treatment of the keyboard. 
[DspStreams] it used to be that character codes below 40b unconditionally called the stream scroll 
procedure. Now, if the character has a non-zero width or height it is displayed. Only characters with zero 
width and height (CR and LF in particular) call scroll. 

Version 18/16 -- May 5, 1980 

Additions: The major addition is that you can now extend a file system by reinstalling the OS. A single 
model 31 file system can be extended to a double model 31, a single model 44 or a double model 44, anaa 
single model 44 can be extended to a double model 44. This is accomplished by a subdialog of the 'long 
installation dialog'. 

Changes: [Calendar] DOs and Dorados now use Alto I clock foitnat. [Dirs] A bug in the 'CompareFn' 
feature has been fixed. [BFS] 'return on check error' is handled better. [InOutLo] Disk error recovery 
during InLd and OutLd has been improved. [DiskStreams] A bug in FilePos, introduced in OS 17 and 
responsible for problems with long files in FrP, has been fixed. Cleanup DiskStream now does the proper 
thing if a file is extended to a multiple of the page size and then trimmed back by less than a page, 
[DisplayStrcams] EraseBits is much faster now because it uses BitBlt. [BfsMl] BitBlt calls Swat if thcBBT 
starts at an odd address. 

Version 17/16 - September 9, 1979 

The most significant Improvements are that the DSK object has been extended to permit disk-independent 
operation at the DoDiskCommand/GetCb level; procedures have been added to scan a disk stream at full 
disk speed; and the directory lookup procedures have been modified to take advantage of these facilities 
and tliereby improve performance substantially. To make way for these improvements, all support for file 
version numbers (a little-used feature) has been removed. 

Incompatibilities are confined to those programs that create DSK objects, since several of the OS routines 
now expect to be passed the extended versions. Programs that include tlie TFS must be reloaded with the 
latest release of IFS; they will then mn under OS 17 or OS 16. Programs that include BFSInit must be 
reloaded with the OS 17 version of BFSInit; they will then not work under previous OS releases. Of the 
standard Alto subsystems, FTP falls into the first category and Neptune in the second. 

In the DSK object, the fields ipDiskDescriptor, driveNumber, retryCount, and totalErrors have moved, 
and fpSysLog has been deleted; it is believed that no existing programs are affected by this. 

Additions: [BFS] the DSK object is extended to include generic procedures InitializeDiskCBZ, 
DoDiskCommand, GetDiskCb, and CloseDisk, and constants lengthCl^ and lengthCBZ. The CBZ 
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structure is now public, and is defined in Disks.d and documented in the "Disks and BFS" description. 
InitializcDiskCiiZ defaults its crrorRtn argument. DoDiskCommand has an optional nextCb argument. 
DcfauUBfsErro/Rtn and BfsNonEx are exported in Sys.bk, so user programs can load BPSInit. ihe BhS 
can now operate in any of the file system partitions available on the large disks of Dorados and DOs. An 
optional hintLastPage argument to ActOnDiskPages, WriteDiskPagcs, and DcleteDiskPages has been 
added. New procedures include Min, Max, Umin, Umax, and CalUO through CalUS. 

[Disk streams] A DiskStreamsScan level has been added, containing the procedures InitScanStream, 
GetScanStrcamBuffcr, and FinishScanStream; these support overlapped reads at full disk speed. 

[Keyboard] Shift-I.F generates Ascii MOB - accent grave. 

Deletions: The remaining vestiges of the Sys.Log code are gone. BFSSetStartingVDA removed -- use 
RcleascDiskPage(disk, AssignDiskPage(disk, dcsiredVDA-l)). All support for version numbers has been 
removed from tlic standard release; an alternate release (NewOsV.boot) is available in which the version 
number facility has been retained, but it does not benefit from the improved directory lookup 
perfoiTnancc, it is somewhat larger, and it may not be supported in the future. 

Changes: levBasic is now guaranteed to be at 175000B or higher, for the benefit of Mesa and Smalltalk. 
RelcaseDiskPage doesn*t increment the page count if die page released is already free. The BFS now 
retries data-late errors indefinitely. The BFS cleanup routine is now called with three arguments. The 
DiskDcscriptor file is now allocated next to SysDir rather than in the middle of the disk as it was in OS 16. 
^rhc old write date is not restored to a directory file (directory bit on in serial number) if the file is opened 
for writing but never dirtied. A number of bugs in the disk streams code have been fixed that prevented 
manipulation of files greater than 32767 pages long. Directory operations (Open File, DeleteFile, etc J now 
search the directory at essentially full disk speed. Booting has been speeded up somewhat. The OS uses 
and maintains disk shape information as a DSHAPE file property in the leader page of SysDir. 

Version 16/16 - February 19, 1979 

This version contains many internal changes but few external ones. Even though it is technically 
incompatible with previous releases (OS 16/16 rather than OS 16/5), most programs are not affected. 
There arc three major changes: 1) backward compatibility for the "old OS has been removed, 2) the disk 
bit table is now paged rather than occupying a fixed area in memory, and 3) the interface between Swat 
and the OS changed - Swat.25 is required. 

Additions: the BitBlt instruction is accessible from Bcpl and a structure definition for a BitBlt table was 
added to AltoDefs.d. More of the page 1 and I/O area location names were added to AltoDefs.d. Anew 
declaration file, BcplFiles.d, was created and Uie Bcpl file format definitions were moved there from 
SysDefs.d. The OS corrects parity in extended memory banks during booting. The "new" file date 
standard is implemented. The DDMgr object operations were added to Calls.asm. 

Deletions: the compatiblity package has been removed. All of the commonly used subsystems which 
depended on it have been updated. They are: Asm, RamLoad, CleanDir, EDP, and Scavenger If you 
keep any of these on your disk, you should get new copies from the <Alto> directory. fpSysLog, IpSysTs, 
f^WorkingDir, faSysLog, and nameWorkingUir went away. 

Reorganiztions: the BFS was extensively reorganized to bring it into sync with the TFS. llie code for 
creating a virgin file system and creating a DSK object has been disentangled from OS inidalization. The 
Bcpl frame-munging code was split out of liFSML.asm and put into a new file: BcplTricks.asm. 
Initialization for the keyboard was moved from the OS initializtion modules into KeyStreamsB.bcpl. 
making it self-contained. Parity Error handling, Calendar clock update. Swat interface, and InOutLdwere 
split into separate modules. 

Changes: Disablelnterrupts returns true if interrupts were on. The VERS and DCB structure were moved 
into AltoDefs.d. The names of many OS modules changed. The long installation dialog permits more 
precise control over the handling of memory errors. The erase disk dialog permits you to create an extra 
big directory. The interface to Swat has changed - Swat.25 is the new version. 

Version 15/5 -- March 15, 1978 
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Fixed a bug in the file date code; introduced another bug in the same code. 

Version 14/5 -- March 1, 1978 

Additions: ReadCalendar and SetCalendar - analogus to DayTimc and SctDaytime only they conform to 
the new time sLuidard. DayTime and SctDaytime will continue work correctly until April 30, 1978. Anew 
declaration file, AltoDefs.d was created; some things were moved there from SysDefs.d. Definitions oftlie 
format of .IVIi (overlay), and .Syms files were added to SysDefs.d. This OS has room for a ^big' bittable -a 
special OS version is not required. 

Deletions: The system log was de-implemented. LogOpen, LogClose, and MakeLogEntry are nowNoops. 
They will be removed when an incompatible OS is next released. 

Reorganizations: Noop, TrucPrcdicatc and FalsePredicate were moved from StrcamsML.asm to 
BFSML.asm (up a few Junta levels). Fast streams were split out of disk streams: FastStreamsB.bcpl and 
FastStcamsA.asm. Streams.bcpl was split into 3 files: DiskStreams.bcpl, DiskStreamsMain.bcpl, and 
DiskStreamsAux.bcpl; StrcamsML.asm disappeared. 

Changes: A bug in ReturnFrom was fixed (this only mattci^s if you use the microcode version of the frame 
allocator). TruePredicate now returns -1 (it used to return 1). If the unrecoverable disk error routine in the 
BFS returns, the cleanup procedure is called and things plunge on. OpenFile with a filename containinga 
non-existant directory now returns instead of calling Swat. The Diablo printer bits (0-7) are nowignored 
by the keyboard interrupt roudne. 

Version 13/5 -- May 16, 1977 

Additions: ParseFilcName (a lower level directory function) was made available to users. 

Changes: Minor, yea insignificant bugs fixed. 

Version 12/5 -- March 20, 1977 

Additions: ClockSecond. Location 613b is now reserved to indicate to RAM microcode what sort of Alto 
we are on: implies Alto I; -1 implies Alto IL 

Changes: Time-keeping accuracy improved slightly. BFS is now reentrant-vou may have several 
independent disk activities going concurrently (this will make CopyDisk more reliable). 

Version 11/5 - January 9, 1977 

Additions: eventlnLd and eventCallSubsys processing added. Also now possible to install the operating 
system with logging disabled. 

Changes: Boodng process somewhat more robust. Several changes to improve diagnostic information 
about parity errors provided by Swat. Improved password protection. Alto II fixes m parity and timer 
routines. 

Version 10/5 -- November 2, 1976 

Changes: A nasty bug in the disk routines was uncovered and fixed. It was responsible for occasionally 
garbaged files. 

Version 9/5 - September 25, 1976 

Additions: verNew Always option to OpenFile; changeSerial entry on file leader pages. 

Changes: Various bugs relating to keeping file version numbers were fixed. 

Version 8/5 - August 28, 1976 
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Changes: Several bugs in parity error detection and reporting were removed. 

Version 7/5 - August 10, 1976 

Additions: The Idle procedure and corresponding static Ivldle; IvParityPhantomEnable global static; more 
installation options. 

Minor changes: Two bugs in PositionPage are fixed -- one permitted read-only files to be accidendy 
lengthened. 

Version 6/5 - July 8, 1976 

Additions: (1) Several global statics have been added: AltoVersion (code for machine, build and 
microcode versions), ErrorLogAddress (Ethernet address to report hardware errors), # 176777 points to 
the global statics. 

(2) The format of Sys.Boot has been altered slightly so that Altos may be booted over the Ethernet 

Version 5/5 - April 28, 1976 

How to get it: Because version 5 introduces some incompatibilities, it is essential that several subsystemsbe 
updated: (1) get a new Executive and Bravo 5.5 or later (these will lOin under version 4 or version 5 of the 



operating system); (2) get Sys.Bk, Sys.Syms, Sys.Boot (under another name. e.g. NewOs.Boot); (3) install 
your new system; (4) get a new version of DDS, which depends on version 5 of the operating system; (5) 
get a new InstallSwatJlun and invoke it; (6) if you are a programmer, be sure to get new copies of all 



Incompatibilities: (1) Most calling sequences and subroutine names for the "Bfs" routines have changed. 
These changes were made in order to mtroduce the concept of a "disk" object, so that standard OS stream 
and directory functions could be applied to non-standard disks (e.g., the Trident T80). The static 
IvDiskKd has been removed. 

(2) The "disk address" returned as part of a CFA or FA is now a virtual disk address. The routine 
RealDiskDA can be used to convert it to a physical disk address if desired. 

Minor changes: (1) The handling of the UserFinishProc has changed. The recommended procedure for 
such procedures is to simply return from a finish procedure, not to call OsFinish again. 

(2) Several bugs in the streams package are fixed, e.g. ReadBlock applied to a file with 511 bytes in die last 
data page did not work correctly. 

(3) The "new disk" refreshing procedure has been changed to use the new FTP; it is now mandatory that 
this file be present on your disk when you attempt to make a brand new disk. 

(4) It is now possible to change disk packs during the Install seguence; simply change packs when some 
question is asked of you (exception: ir you are creating a "new disk," do not change packs until told to do 
so). 

(5) The log functions have been made much more robust. It is now possible to delete Sys.Log and 
continue operations. 

(6) Numerous bugs in ReturnFrom and FramesCaller are fixed. 

(7) The default number of file versions to keep is now stored in the DiskDescriptor. 

(8) Wns has been changed to allow both signed and unsigned number conversion. 

(9) The arguments to DeleteFile have changed slightly (only if you pass more than 2 arguments to it). 
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(10) The introduction of the *'disk" object has added some statics: sysDisk, some functions: KsGetDisk, 
l.nl^ageSizc, and optional "disk" arguments to disk stream opening functions. 



